Skip to content

docs(kalshi): document Edge Connect teardown in the runbook - #200

Merged
Jared-dz merged 1 commit into
mainfrom
bdz/kalshi-runbook-teardown
Aug 28, 2026
Merged

docs(kalshi): document Edge Connect teardown in the runbook#200
Jared-dz merged 1 commit into
mainfrom
bdz/kalshi-runbook-teardown

Conversation

@ben-dz

@ben-dz ben-dz commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

The Kalshi runbook ends at "Confirm data path" with no removal path, so the only uninstall guidance for Edge Connect lives in the bridge repo's README. An agent driving this runbook via get_onboarding_runbook has nothing to offer a user who asks how to undo it.

Adds a ## Teardown section and one gotcha.

The part worth reviewing is the correctness claim, not the prose. docker stop is the uninstall: the entrypoint stays PID 1 specifically so its TERM trap can run a bounded doublezero disconnect while the daemon is still up, and the installer sets --stop-timeout 60 to give it room. So a manual doublezero disconnect first is redundant — but docker rm -f or docker kill bypasses the trap and orphans the onchain session and doublezero1 in the host netns. That is gotcha 8 ("Stale doublezero1") arriving self-inflicted, and it was documented nowhere user-facing; connect.sh warns about it only in its own reinstall path. The verification step uses ip link show doublezero1 rather than doublezero status, since the latter is only reachable through docker exec and the container is gone by then.

Sources: docker-entrypoint.sh (the trap and its SIGNALED/dz_connected guards), scripts/connect.sh (--stop-timeout 60, and the orphaned-iface warning it emits after a failed graceful stop).

Blocker — this page is already truncated

Not introduced here, but it makes this PR ineffective on its own. The MCP fetches runbooks through docsfetch, which hard-cuts every page at MaxPageBytes = 10000. This page is 11,086 bytes on main, so the model already never sees the tail — the cut lands mid-sentence in gotcha 7, dropping gotcha 8, the consumer sketch and See also. The section added here sits past that cut.

It is systemic, not specific to this page. 9 of the 20 MCP-served pages are over the limit: troubleshooting at 21,033 bytes loses 52% of itself, contribute 43%, and kalshi, contribute-operations, geolocation, glossary, setup and multicast-admin are all cut. That is worth its own issue against lake.

So: merge this for the content and the docs site, but the MCP will not serve it until MaxPageBytes is raised or these pages are trimmed. Happy to trim this page under 10,000 in this PR instead if that is the call.

The runbook ends at 'Confirm data path' with no removal path, so the only
uninstall guidance for Edge Connect lives in the bridge repo's README.

Add a Teardown section covering the part that is easy to get wrong: 'docker
stop' is the uninstall, because the entrypoint stays PID 1 so its TERM trap
can run a bounded 'doublezero disconnect' before the daemon goes down. A
'docker rm -f' or 'docker kill' bypasses that trap and orphans the onchain
session and doublezero1 in the host netns.

@Jared-dz Jared-dz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good item to document

@Jared-dz
Jared-dz merged commit db1823d into main Aug 28, 2026
7 checks passed
ben-dz added a commit to malbeclabs/lake that referenced this pull request Aug 31, 2026
`docsfetch` cut every MCP-served docs page at `MaxPageBytes = 10000`.
Measured against `malbeclabs/docs@751d45b`, that truncates **12 of the
27 MCP-reachable slugs**:

| bytes | page | | bytes | page |
|---|---|---|---|---|
| 33,856 | contribute-provisioning | | 12,200 | Swapping-sol-to-2z |
| 21,551 | troubleshooting | | 11,789 | geolocation |
| 17,551 | contribute | | 11,693 | glossary |
| 14,975 | contribute-ops-management | | 11,086 | kalshi-runbook |
| 13,694 | contribute-operations | | 10,880 | setup |
| 12,397 | kalshi | | 10,648 | multicast-admin |

The bound arrived in #770 as a defensive constant, not a measured one.
It was also silent — a bare `... (truncated)` appended to the content
string and no signal anywhere else — which is why this went unnoticed.
For `get_onboarding_runbook` it means an agent walks a user through a
procedure with the tail of the runbook missing.

Raises the bound to 64 KiB (~2x the largest real page), makes the marker
name the byte count and the source URL so an agent can point the user at
the rest, and reports `truncated` on both tool outputs.

Three things worth a reviewer's attention:

**The chat agent had its own copy of the fetch**, still bounded at
10,000 with the old silent marker, so the raised bound would not have
reached web or Slack users. `readDocs` in
`agent/pkg/workflow/v3/pipeline.go` now calls `docsfetch.Client.Read` —
a net −55 lines, and it picks up two things it never had: the
`ValidPage` slug guard (it previously interpolated the page straight
into a raw.githubusercontent URL) and a request timeout.

**A truncated runbook index is a hard error, not a short catalog.**
`loadRunbookCatalog` parses `runbooks.md` into the list of known
services; a cut index silently drops entries, and
`get_onboarding_runbook` then answers `unknown runbook "kalshi"` for a
runbook that exists. That is a confident wrong answer rather than a
degraded one, so it fails instead. It is the only `Read` call site whose
result the handler branches on.

**All three truncation cases now log at WARN.** The in-band marker
reaches the model but not an operator; the index refusal takes the tool
down for every caller, so it is the one that most needed a line.

`read_docs` also advertises three pages that no longer exist and one
that is an HTML redirect stub — in both the MCP and agent tool
descriptions. Real, but a separate change.

## Testing Verification

`TestRead_LargestRealPageIsNotTruncated` pins a 34,000-byte page reading
back whole; red-checked against the old constant, where it fails. The
marker's wording is asserted in `docsfetch`, which runs without
containers.

No test here can catch a docs page crossing the bound — nothing in lake
knows those sizes, they are fetched at runtime from another repo. Loud
truncation is the mitigation chosen over a cross-repo CI size check.

Two gaps, both environmental: the four new `api/handlers` tests and the
eval suite were **not executed locally**, since both packages'
`TestMain` starts containers and Docker was unavailable. Both compile
and vet clean. No eval references `read_docs`, so the agent change is
unexercised by that suite either way; `agent/pkg/workflow/v3` unit tests
pass.

`make lint` and `go build ./...` fail identically on `main`
(`dev/controlcenter` needs a built UI bundle). Both clean when scoped to
the touched packages.

## Blocks

malbeclabs/docs#200 — its new `## Teardown` section lands past the old
cut on `kalshi-runbook.md` (11,086 bytes). The alternative offered
there, trimming the page under 10,000, is not the fix taken.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants